package com.gitee.wsl.collections.map.api


/**
 * Defines a map that holds a list of values against each key.
 *
 *
 * A `ListValuedMap` is a Map with slightly different semantics:
 *
 *
 *  * Putting a value into the map will add the value to a [List] at that key.
 *  * Getting a value will return a [List], holding all the values put to that key.
 *
 *
 * @param <K> the type of the keys in this map
 * @param <V> the type of the values in this map
 * @since 4.1
</V></K> */
interface ListValuedMap<K, V> : MultiValuedMap<K, V> {
    /**
     * Gets the list of values associated with the specified key.
     *
     *
     * This method will return an **empty** list if
     * [.containsKey] returns `false`. Changes to the
     * returned list will update the underlying `ListValuedMap` and
     * vice-versa.
     *
     *
     * @param key  the key to retrieve
     * @return the `List` of values, implementations should return an
     * empty `List` for no mapping
     * @throws NullPointerException if the key is null and null keys are invalid
     */
    override fun get(key: K): List<V>

    /**
     * Removes all values associated with the specified key.
     *
     *
     * The returned list *may* be modifiable, but updates will not be
     * propagated to this list-valued map. In case no mapping was stored for the
     * specified key, an empty, unmodifiable list will be returned.
     *
     *
     * @param key  the key to remove values from
     * @return the `List` of values removed, implementations
     * typically return an empty, unmodifiable `List` for no mapping found
     * @throws UnsupportedOperationException if the map is unmodifiable
     * @throws NullPointerException if the key is null and null keys are invalid
     */
    override fun remove(key: K): List<V>
}
